home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Turnbull China Bikeride
/
Turnbull China Bikeride - Disc 2.iso
/
STUTTGART
/
NEWSOFT
/
AUGUST
/
MESSENGER
/
!Messenger
/
Resources
/
THSoundDoc
< prev
Wrap
Text File
|
1996-12-12
|
5KB
|
148 lines
THSound
=======
by:
Tony Houghton
271 Upper Weston Lane
Southampton
SO19 9HY
tonyh@tcp.co.uk
Version 1.20
The purpose of THSound is to allow many different samples to be played
without having to load each one as a module in its own right (often
impractical due to potential name clashes). All it does is take a pointer to
some data in raw 8-bit VIDC format and use this to make a sound voice.
THSound is deliberately very basic for flexibility. It is up to your program
to manage memory for the sample data, and to attach the voice to channels and
play it using the standard Sound SWIs.
I wrote THSound because I was writing a program which needed to play a large
number of samples, the data for these being embedded in large files with
other resources. I couldn't find a PD program which could do what I wanted
(other modules only seem to be able to load samples as files) so I studied
the PRM and THSound was born.
Conditions of use
-----------------
THSound may be freely distributed. It may be used in applications provided it
is unaltered and you credit me, the author. If possible, please include this
file with it (I know that won't always be possible), or at least indicate
that it is available with instructions from PD libraries. As a courtesy it
would be very nice if you send me copies of any programs you write which use
it.
Technical details
=================
THSound contains three SWIs for sound sample handling; its SWI chunk is
&4B780 (officially registered with Acorn).
SWI's
-----
THSound_InstallSample &4b780
Entry: R0 = Address of sample (in VIDC 8-bit signed log format)
R1 = Size of sample in bytes (word aligned)
R2 = Slot to install in or 0 for next free slot (see
Sound_InstallVoice)
Exit: R0 = Sample's "handle" (pointer to workspace)
R1 = Voice slot sample is installed in
R2 = Voice slot (copy of R1)
It is recommended that sample data is kept in the RMA, using OS_Module for
memory management (Archimedes), or in a dynamic area (Risc PC). Having sample
data in application workspace could crash SoundDMA if the application is
paged out eg by Wimp_Poll while the sample is playing.
Each sample's voice is given the name THSVoice<hh> where <hh> is a unique hex
code.
THSound_RemoveSample &4b781
Entry: R0 = Sample's handle
Exit: R0 Preserved
Use this to kill a THSound sample, do not use Sound_RemoveVoice. The sample's
data is not freed, just its workspace (handle) allocated when it was
installed.
THSound_GetVoiceSlot &4b782
Entry: R0 = Sample's handle
Exit: R0 Preserved
R1 = Voice slot
Finds the sample's voice slot in case you haven't stored the value returned
by THSound_InstallVoice.
THSound_ChannelInUse &4b783
Entry: R0 = Channel number
Exit: R0 Non-zero if a THSound sample is playing on specified channel.
New in version 1.10, remember to check the version if you use this SWI.
This reads data from the SCCB to test whether a THSound voice is
currently playing (it won't work for most other samples, because THSound
uses the SCCB in a slightly non-standard way). The necessary information
in the SCCB is invalid immediately after calling Sound_Control and may
wrongly show the channel not to be in use, so if you want to wait for a
channel to become free you should use something like:
REM First wait for SCCB to be updated, showing channel is in use
REPEAT
SYS"THSound_ChannelInUse",1 TO inuse%
UNTIL inuse%
REM Now wait until channel is free
REPEAT
SYS"THSound_ChannelInUse",1 TO inuse%
UNTIL NOT inuse%
The second loop can be after, say, a Wimp_Poll, but I suggest you put
the first loop immediately after a Sound_Control (or similar)
instruction.
THSound_GetPollWord &4b784
Entry: R0 = Sample's handle
Exit: R0 Preserved
R1 = (Pointer to) poll word
New in version 1.20
This is more useful than THSound_ChannelInUse for multitasking programs.
Before playing a sample you can set the pollword to 0, and it will be
altered when the sample finishes playing or is interrupted by being detached
from its channel. Therefore you can use PollWordNonZero Wimp events to
receive notification.
If the sample finishes playing without being interrupted, -1 or &FFFFFFFF
will be written to the pollword, otherwise another non-zero value will be
written.
THPlay
======
THPlay is a short BASIC program that can be used to play a sample in the
background. It must be given a file containing raw sample data in 8-bit VIDC
format, using the -file parameter in its command line. THPlay loads the
sample into the RMA, starts playing it, then polls the Wimp until it has
finished playing or a time limit is reached. Then THPlay releases the sample
and its memory and quits.
Other parameters are optional and are:
Parameter Default Meaning
--------- ------- -------
-chan 1 Channel to play sample on
-vol &17F Volume to play sample at
-pitch &2000 Pitch to play sample at
-maxtime 10 Maximum time in seconds before sample is killed
THPlay requires at least a 12K WimpSlot. You might like to run it via an Obey
file to ensure THSound gets loaded first and that THPlay isn't allocated an
unnecessarily large Wimpslot. For example:
RMEnsure THSound 1.20 RMLoad <Obey$Dir>.THSound
WimpSlot -min 12k -max 12k
<Obey$Dir>.THPlay -pitch &3000 -file %0